feat: rework PlanDisplay to Plans 2.0 design - #170

📐 Maintainability & Code Quality | 🟠 Major | ⚡ Quick win

Fix CHANGELOG format to match repository contract (headers + PR references).

Line 7–13 uses non-standard headers and omits mandatory PR references in entries. Please switch to the required category names/emojis and include ([#PR](full-url) by [@contributor](profile-url)) for each item.

As per coding guidelines, "Use the following category headers with emojis: 🛠 Breaking changes, 🎉 New features, 🐛 Bug fixes, 📚 3rd party library updates, and 💡 Others" and "Each changelog entry must follow the format: Description... ([#PR](...) by [@contributor](...))". As per path instructions, "Ensure CHANGELOG.md updates follow the established format ... Each entry must include PR reference and author."

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@packages/react/src/components/PlanDisplay/CHANGELOG.md` around lines 7 - 13,
The CHANGELOG.md file uses non-standard headers and incomplete PR references
that don't match the repository contract. Update the category headers from "###
✨ Features" to "### 🎉 New features" and from "### ⚠️ Breaking changes" to "###
🛠 Breaking changes". Ensure each changelog entry follows the required format by
including the complete PR reference as `([`#PR`](full-url) by
[`@contributor`](profile-url))` at the end of each item description. The entries
mentioning the PlanDisplay rework and the highlighted prop removal need to have
their PR references properly formatted with the full GitHub URL and contributor
profile URL.

Sources: Coding guidelines, Path instructions

🎯 Functional Correctness | 🟡 Minor | ⚡ Quick win

Avoid nesting a default Box inside Text as="span".

On Line 17, Box is rendered inside Text as="span". If Box renders as a block element, this creates invalid HTML nesting and can cause inconsistent layout/semantics. Render that inner Box as a span (or remove the wrapper).

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In
`@packages/react/src/components/PlanDisplay/src/components/PlanDisplayBullet/PlanDisplayBullet.tsx`
around lines 14 - 19, The Box component is nested inside the Text component that
renders as a span (inline element), which creates invalid HTML when Box renders
as a block element. To fix this, modify the Box component to render as a span by
adding the as="span" prop, or if the Box wrapper is not necessary for layout
purposes, remove it entirely and place the icon directly inside the Text
component with appropriate flex styling applied to the Text element instead.

📐 Maintainability & Code Quality | 🟠 Major | ⚡ Quick win

Remove inline style usage in the badge wrapper.

Line 32 introduces a custom inline style (style={{ verticalAlign: "middle" }}), which violates repository styling rules. Please replace this with design-system-supported props/layout primitives.
As per coding guidelines **/*.{tsx,ts,scss,css}: Do NOT use custom styles in this repository; never use custom SCSS/CSS.

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In
`@packages/react/src/components/PlanDisplay/src/components/PlanDisplayBullet/PlanDisplayBullet.tsx`
around lines 28 - 33, Remove the inline style prop containing verticalAlign:
"middle" from the Box component wrapper in the PlanDisplayBullet component.
Replace it with design-system-supported alignment props instead. Since the
intent is vertical alignment, use the appropriate Box layout prop (such as
alignItems) that matches the design system's conventions for handling vertical
centering, removing the custom inline style entirely.

Source: Coding guidelines

📐 Maintainability & Code Quality | 🟠 Major | ⚡ Quick win

Use an interface for PlanDisplayBulletProperties in .types.ts.

PlanDisplayBulletProperties is currently declared as a type alias. Repository rules for *.types.ts require ComponentNameProperties to be an exported interface.

As per coding guidelines, "**/*.types.ts: Export a ComponentNameProperties interface following PascalCase convention..." As per path instructions, "**/*.types.ts: Always export a 'ComponentNameProperties' interface..."

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In
`@packages/react/src/components/PlanDisplay/src/components/PlanDisplayBullet/planDisplayBullet.types.ts`
around lines 3 - 10, Convert the PlanDisplayBulletProperties type alias to an
exported interface. Replace the type keyword and assignment syntax with
interface syntax, keeping all the properties (icon, disabled, badge) and their
JSDoc comments intact. This aligns with the repository's coding guidelines that
require ComponentNameProperties to be exported as an interface in *.types.ts
files.

Sources: Coding guidelines, Path instructions

📐 Maintainability & Code Quality | 🔵 Trivial | ⚡ Quick win

Add a precedence test for ribbonLabel over gradient.

The public contract documents that ribbonLabel overrides gradient, but this behavior is not directly tested. Add a case passing both props and asserting the ribbon path is rendered.

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In
`@packages/react/src/components/PlanDisplay/src/components/PlanDisplayCard/planDisplayCard.spec.tsx`
around lines 21 - 32, Add a new test case in the planDisplayCard.spec.tsx file
that verifies the precedence behavior where ribbonLabel overrides gradient when
both props are provided. Create a test using makeSut that passes both gradient:
true and a ribbonLabel value, then assert that the ribbon label text is
rendered, confirming that the ribbon takes precedence over the gradient variant
as documented in the public contract.

📐 Maintainability & Code Quality | 🟠 Major | ⚡ Quick win

Add component JSDoc and explicit displayName.

PlanDisplayCardPrice is missing component-level JSDoc and PlanDisplayCardPrice.displayName, both required by the TSX standards in this repo.

+/**
+ * Renders the pricing block for a plan card, including current price and optional
+ * previous price, billing period, and annual note.
+ */
 const PlanDisplayCardPrice: React.FC<PlanDisplayCardPriceProps> = ({
   price,
   previousPrice,
   period,
   annualNote,
 }) => (
   <Box display="flex" flexDirection="column" gap="2">
@@
   </Box>
 );
 
+PlanDisplayCardPrice.displayName = "PlanDisplayCardPrice";
+
 export { PlanDisplayCardPrice };

As per coding guidelines, "Set the displayName property for each component and sub-component in React" and "Document all React components with JSDoc comments including description and prop documentation."

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In
`@packages/react/src/components/PlanDisplay/src/components/PlanDisplayCardPrice/PlanDisplayCardPrice.tsx`
around lines 5 - 44, The PlanDisplayCardPrice component is missing required
documentation and displayName property per the repo's TSX standards. Add a JSDoc
comment block above the component definition that includes a description of the
component's purpose and documents all props (price, previousPrice, period,
annualNote) with their types and descriptions. Additionally, add
PlanDisplayCardPrice.displayName = "PlanDisplayCardPrice" after the component
export to explicitly set the display name for debugging and React DevTools
identification.

Sources: Coding guidelines, Path instructions

📐 Maintainability & Code Quality | 🟠 Major | ⚡ Quick win

Remove inline custom styling from previousPrice rendering.

This introduces custom styling in a .tsx file (style={{ ... }}), which violates repository styling policy. Use Nimbus-supported props/tokens only (or expose the token through the design-system API) instead of inline CSS.

As per coding guidelines, "**/*.{tsx,ts,scss,css}: Do NOT use custom styles in this repository; never use custom SCSS/CSS."

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In
`@packages/react/src/components/PlanDisplay/src/components/PlanDisplayCardPrice/PlanDisplayCardPrice.tsx`
around lines 20 - 24, Remove the inline style object from the previousPrice span
element in PlanDisplayCardPrice.tsx that contains custom color and
textDecoration properties. Replace this inline styling with appropriate Nimbus
design-system tokens and props. Check if Nimbus provides component props or
token utilities for applying neutral-interactivePressed color and line-through
text decoration, and use those instead of the style={{ }} object.

Sources: Coding guidelines, Path instructions

📐 Maintainability & Code Quality | 🟠 Major | ⚡ Quick win

Use an exported PlanDisplayCardPriceProperties interface (with top-level JSDoc).

In *.types.ts, this repository requires ComponentNameProperties to be exported as an interface. Here it is a type alias. Also add top-level JSDoc for exported types (not only field-level comments).

 import { ReactNode } from "react";
 
-export type PlanDisplayCardPriceProperties = {
+/**
+ * Properties contract for PlanDisplayCardPrice.
+ */
+export interface PlanDisplayCardPriceProperties {
@@
-};
+}
 
+/**
+ * Public props alias for PlanDisplayCardPrice.
+ */
 export type PlanDisplayCardPriceProps = PlanDisplayCardPriceProperties;

As per path instructions, "**/*.types.ts: Always export a 'ComponentNameProperties' interface ..." and "Use proper JSDoc comments for all exported types`."

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In
`@packages/react/src/components/PlanDisplay/src/components/PlanDisplayCardPrice/planDisplayCardPrice.types.ts`
around lines 3 - 27, Convert the PlanDisplayCardPriceProperties type alias to an
interface declaration and add a top-level JSDoc comment above it. Change the
`export type PlanDisplayCardPriceProperties = { ... }` syntax to `export
interface PlanDisplayCardPriceProperties { ... }` and add a descriptive JSDoc
comment above the interface that explains what this type represents, keeping the
existing field-level JSDoc comments intact.

Sources: Coding guidelines, Path instructions

📐 Maintainability & Code Quality | 🔵 Trivial | ⚡ Quick win

Let consumer spacing props override the default margin.

Line 8 applies my="3" after spreading props, which blocks callers from overriding margin. For better composability, set defaults before spreading props.

-  <Box {...props} my="3">
+  <Box my="3" {...props}>
     <Divider />
   </Box>

As per path instructions **/*.{ts,tsx}: review for component reusability and composability.

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In
`@packages/react/src/components/PlanDisplay/src/components/PlanDisplayCardSpacing/PlanDisplayCardSpacing.tsx`
at line 8, The Box component in PlanDisplayCardSpacing.tsx currently has the
my="3" margin applied after the {...props} spread, which prevents consumers from
overriding the default margin value. Reorder the attributes so that the default
spacing (my="3") is set before spreading the props, allowing any margin-related
props passed by consumers to override the default. Change the order from
`{...props} my="3"` to `my="3" {...props}`.

Source: Path instructions

📐 Maintainability & Code Quality | 🟡 Minor | ⚡ Quick win

Add controls for the newly exposed PlanDisplay props, not only visibility toggles.

Line 155–184 currently exposes boolean toggles only; key API inputs like ribbonLabel, gradient, price, previousPrice, period, and annualNote content aren’t controllable from Storybook controls, which weakens discoverability of the new surface.

As per coding guidelines, "**/*.stories.{ts,tsx}: Add controls for all component props in Storybook stories."

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@packages/react/src/components/PlanDisplay/src/planDisplay.stories.tsx` around
lines 155 - 184, The Playground story object only exposes boolean visibility
toggles through PlaygroundArgs type and argTypes, but does not include controls
for important content props like ribbonLabel, gradient, price, previousPrice,
period, and annualNote. Add these missing props to the PlaygroundArgs type
definition with appropriate types, provide default values for each in the args
object, and define corresponding controls in the argTypes object using
appropriate control types (text for string values, number for numeric values,
etc.) to make all component props discoverable and configurable in Storybook.

Source: Coding guidelines

Bug: PlanDisplay.Price's generated docs come out empty because of this displayName.

Every other subcomponent here sets its public displayName to its internal component name so it matches the <Name>Properties type the docs generator (@nimbus-ds/scripts Docgen) looks up — e.g. PlanDisplay.Header.displayName = "PlanDisplay.CardHeader" resolves to PlanDisplayCardHeaderProperties. Price breaks that pattern: it's set to the public name "PlanDisplay.Price", so the generator looks for a type named PlanDisplayPriceProperties, but the actual exported type is PlanDisplayCardPriceProperties (in planDisplayCardPrice.types.ts).

I confirmed this by running yarn build:docs on this branch — it prints:

⚠️  Schema generation skipped for PlanDisplayPriceProperties: type PlanDisplayPriceProperties not found

and the resulting planDisplay.docs.json entry for PlanDisplay.Price comes out as {"name": "PlanDisplay.Price", "totalProps": 0, "props": []} — the flagship new subcomponent of this PR ships with zero documented props.

Also, planDisplay.docs.json itself was never regenerated in this PR at all (its diff against master is empty), even though props were added/removed/renamed across Card, Bullet, Header. Per .cursor/rules/json-docs.mdc this file must be regenerated via yarn build:docs after type changes — right now the published docs still show the removed highlighted prop and are missing gradient, ribbonLabel, tag, badge, icon, and PlanDisplay.Price entirely.

Fix: rename this to PlanDisplay.Price.displayName = "PlanDisplay.CardPrice"; (matching the type name), then run yarn build:docs and commit the regenerated planDisplay.docs.json.

This should be a major release, not minor. This PR removes the public highlighted prop from PlanDisplay.Card (see planDisplayCard.types.ts), which the CHANGELOG in this same PR correctly labels a "🛠/⚠️ Breaking change" and versions as 2.0.0. A minor release entry here means yarn bump:stable will actually bump @nimbus-ds/plan-display to 1.2.0, not 2.0.0 — contradicting the CHANGELOG and shipping a breaking API removal under a non-major version, which silently breaks consumers pinned with ^1.x.

This is also exactly the case the repo's own .coderabbit.yaml custom_checks.Unversioned Breaking Changes is designed to catch: "All breaking changes MUST have a MAJOR version bump (x.0.0)."

Please change this to:

releases:
  "@nimbus-ds/plan-display": major
  "@nimbus-ds/patterns-webpack": patch

Formatting deviates from .cursor/rules/changelogs.mdc in two ways that matter beyond nitpicking, because the second one is also literally what the repo's custom_checks."Breaking Change Documentation Verification" cross-references for:

1. Category headers should be #### (not ###) with the exact emojis 🎉 New features and 🛠 Breaking changes (not ✨ Features / ⚠️ Breaking changes). The automated check looks for the literal string "🛠 Breaking changes" — as written, this section won't match it.
2. Entries are missing the PR reference link. The rule's required format is - Description. ([#PR](url) by [@contributor](url)); both bullets here only have the contributor link, no [#170](https://github.com/TiendaNube/nimbus-patterns/pull/170).

Suggested fix:

#### 🎉 New features

- Reworked `PlanDisplay` to the Plans 2.0 design... ([#170](https://github.com/TiendaNube/nimbus-patterns/pull/170) by [@noecondoleo](https://github.com/noecondoleo))

#### 🛠 Breaking changes

- Removed the legacy `highlighted` prop on `PlanDisplay.Card`... ([#170](https://github.com/TiendaNube/nimbus-patterns/pull/170) by [@noecondoleo](https://github.com/noecondoleo))

This drops the Card import from @nimbus-ds/components entirely and rebuilds the card chrome (shadow, border, radius, overflow, ribbon, gradient) with two native <div>s and hand-written inline styles / raw CSS variables. That's a direct conflict with two explicit project rules: .cursor/rules/components.mdc ("We do NOT use custom styles in this repository. NEVER use custom SCSS/CSS") and .coderabbit.yaml's review instructions ("Consistent usage of @nimbus-ds/components, instead of native HTML elements").

I verified the stated justification in the comment on lines 59-62 — @nimbus-ds/components' Box really does silently discard the style prop at runtime (its dist/Box/index.js destructures style from props and then never uses it, using only the sprinkle-generated style instead) — so falling back to a native element for margin-top: auto / a custom gradient is a real, verified constraint, not an invented one. Given that, this is more of a design-system limitation than a bug in this PR.

That said, worth reconsidering before merging:

• Several of the values hardcoded here as raw CSS vars (backgroundColor, paddingTop/paddingBottom, borderTopLeftRadius/borderTopRightRadius) are expressible through Box's own token props (backgroundColor, pt/pb) — only the per-corner radius and the gradient/margin-top:auto seem to genuinely need the escape hatch. Narrowing the native-element usage to just what's unavoidable would reduce the surface that's now unstyleable via the design system's normal props.
• PlanDisplayCardContent (unchanged in this PR) still renders <Card.Body> as a child of this now-Card-less wrapper. Card.Body doesn't require a <Card> ancestor to render correctly (confirmed — it's a self-contained padded box), but it's a bit of an inconsistent signal to keep the DS's Card.Body while replacing its sibling <Card> with hand-rolled divs.
• Since Box silently ignoring style is a real footgun (it's still typed as accepted, so this compiles fine while doing nothing), it might be worth filing that as an issue against @nimbus-ds/components — other component authors are likely to hit this same silent no-op.

Same native-<div>-for-style pattern as PlanDisplayCard (justified — Box does drop style, see the other comment on PlanDisplayCard.tsx), but this one also drops the existing <PlanDisplayCardSpacing /> subcomponent in favor of re-implementing the same divider inline (<Box mt="3" mb="3"><Divider /></Box> here vs. PlanDisplayCardSpacing, which after this PR is literally <Box my="3"><Divider /></Box>). Minor, but it's now duplicated in two places with slightly different spacing props (mt+mb vs my) for what should be the same visual divider — worth reusing <PlanDisplayCardSpacing /> here instead, both for DRYness and so a future spacing change doesn't need to be made in two files.